3D Graphics Programming with QuickDraw 3D 1.5.4

Writing in a View

QuickDraw 3D provides routines that you can use to manage the process of writing a view's data to a file. The view must already exist and be fully configured before you call these routines.

Q3View_StartWriting

You can use the Q3View_StartWriting function to start writing to a file.



 
TQ3Status Q3View_StartWriting (

                     TQ3ViewObject view, 

                     TQ3FileObject file);

view: A view.
file: A file object.

DESCRIPTION

The Q3View_StartWriting function begins the process of writing in the view specified by the view parameter, using the file object specified by the file parameter. After calling Q3View_StartWriting , you specify the model (for instance, by calling Q3Geometry_Submit ). When you have completely specified that model, you should call Q3View_EndWriting to complete the write operation. The renderer attached to the specified view might need to reprocess the model data, so you should always call Q3View_StartWriting and Q3View_EndWriting in a writing loop.

SPECIAL CONSIDERATIONS

You should not call Q3View_StartWriting while writing is already occurring.

Q3View_EndWriting

You can use the Q3View_EndWriting function to end writing to a file.



 
TQ3ViewStatus Q3View_EndWriting (TQ3ViewObject view);

view: A view.

DESCRIPTION

The Q3View_EndWriting function returns, as its function result, a view status value that indicates the current state of the writing in the view specified by the view parameter. Q3View_EndWriting returns one of these four values:



 
typedef enum TQ3ViewStatus {

    kQ3ViewStatusDone,

    kQ3ViewStatusRetraverse,

    kQ3ViewStatusError,

    kQ3ViewStatusCancelled

} TQ3ViewStatus;

If Q3View_EndWriting returns kQ3ViewStatusDone , the writing has been completed and the specified view is no longer in writing mode. At that point, it is safe to exit your writing loop.

If Q3View_EndWriting returns kQ3ViewStatusRetraverse , the writing has not yet been completed. You should respecify the model by reentering your writing loop.

If Q3View_EndWriting returns kQ3ViewStatusError , the writing has failed because the renderer associated with the view encountered an error in processing the model. You should exit the writing loop.

If Q3View_EndWriting returns kQ3ViewStatusCancelled , the writing has been canceled. You should exit the writing loop.

SPECIAL CONSIDERATIONS

You should call Q3View_EndWriting only if writing is already occurring.